{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Tce3stUlHN0L"
      },
      "source": [
        "##### Copyright 2025 Google LLC."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "cellView": "form",
        "id": "tuOe1ymfHZPu"
      },
      "outputs": [],
      "source": [
        "# @title Licensed under the Apache License, Version 2.0 (the \"License\");\n",
        "# you may not use this file except in compliance with the License.\n",
        "# You may obtain a copy of the License at\n",
        "#\n",
        "# https://www.apache.org/licenses/LICENSE-2.0\n",
        "#\n",
        "# Unless required by applicable law or agreed to in writing, software\n",
        "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
        "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
        "# See the License for the specific language governing permissions and\n",
        "# limitations under the License."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "agmT3hrjsffX"
      },
      "source": [
        "# Gemini API: Embedding Quickstart with REST\n",
        "\n",
        "<a target=\"_blank\" href=\"https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/rest/Embeddings_REST.ipynb\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" height=30/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "025c6c81c576"
      },
      "source": [
        "<!-- Princing warning Badge -->\n",
        "<table>\n",
        "  <tr>\n",
        "    <!-- Emoji -->\n",
        "    <td bgcolor=\"#f5949e\">\n",
        "      <font size=30>⚠️</font>\n",
        "    </td>\n",
        "    <!-- Text Content Cell -->\n",
        "    <td bgcolor=\"#f5949e\">\n",
        "      <h3><font color=black>This notebook requires paid tier rate limits to run properly.<br>  \n",
        "(cf. <a href=\"https://ai.google.dev/pricing#veo2\"><font color='#217bfe'>pricing</font></a> for more details).</font></h3>\n",
        "    </td>\n",
        "  </tr>\n",
        "</table>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "JMNKdTpTGZET"
      },
      "source": [
        "This notebook provides quick code examples that show you how to get started generating embeddings using `curl`.\n",
        "\n",
        "You can run this in Google Colab, or you can copy/paste the `curl` commands into your terminal.\n",
        "\n",
        "To run this notebook, your API key must be stored it in a Colab Secret named GOOGLE_API_KEY. If you are running in a different environment, you can store your key in an environment variable. See [Authentication](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb) to learn more."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {
        "id": "R-Vw_mOM_WD0"
      },
      "outputs": [],
      "source": [
        "import os\n",
        "from google.colab import userdata"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "id": "wCkLTpb3oTXE"
      },
      "outputs": [],
      "source": [
        "os.environ['GEMINI_API_KEY'] = userdata.get('GEMINI_API_KEY')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "tjGqGBZ9yARd"
      },
      "source": [
        "## Embed content\n",
        "\n",
        "Call the `embed_content` method with the `gemini-embedding-001` model to generate text embeddings:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 20,
      "metadata": {
        "id": "eA7I_Ww8IETn"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "  \"embedding\": {\n",
            "    \"values\": [\n",
            "      -0.02342152,\n",
            "      0.01676572,\n",
            "      0.009261323,\n",
            "      -0.06383,\n",
            "      -0.0026262768,\n",
            "      0.0010187156,\n",
            "      -0.01125684,\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "\n",
        "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GEMINI_API_KEY\" \\\n",
        "-H 'Content-Type: application/json' \\\n",
        "-d '{\"model\": \"models/gemini-embedding-001\",\n",
        "    \"content\": {\n",
        "    \"parts\":[{\n",
        "      \"text\": \"Hello world\"}]}, }' 2> /dev/null | head"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "x7ngWdZ7yDHp"
      },
      "source": [
        "# Batch embed content\n",
        "\n",
        "You can embed a list of multiple prompts with one API call for efficiency.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 21,
      "metadata": {
        "id": "Z0b35xv5Ja_d"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "  \"embeddings\": [\n",
            "    {\n",
            "      \"values\": [\n",
            "        -0.022374554,\n",
            "        -0.004560777,\n",
            "        0.013309286,\n",
            "        -0.0545072,\n",
            "        -0.02090443,\n",
            "--\n",
            "        0.018649898,\n",
            "        0.01224912\n",
            "      ]\n",
            "    },\n",
            "    {\n",
            "      \"values\": [\n",
            "        -0.007975887,\n",
            "        -0.02141119,\n",
            "        -0.0016711014,\n",
            "        -0.061006967,\n",
            "        -0.010629714,\n",
            "--\n",
            "        -0.016098795,\n",
            "        -0.0049570287\n",
            "      ]\n",
            "    },\n",
            "    {\n",
            "      \"values\": [\n",
            "        -0.0047850125,\n",
            "        0.008764064,\n",
            "        0.0062852204,\n",
            "        -0.017785408,\n",
            "        -0.02952513,\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "\n",
        "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents?key=$GEMINI_API_KEY\" \\\n",
        "-H 'Content-Type: application/json' \\\n",
        "-d '{\"requests\": [{\n",
        "      \"model\": \"models/gemini-embedding-001\",\n",
        "      \"content\": {\n",
        "      \"parts\":[{\n",
        "        \"text\": \"What is the meaning of life?\"}]}, },\n",
        "      {\n",
        "      \"model\": \"models/gemini-embedding-001\",\n",
        "      \"content\": {\n",
        "      \"parts\":[{\n",
        "        \"text\": \"How much wood would a woodchuck chuck?\"}]}, },\n",
        "      {\n",
        "      \"model\": \"models/gemini-embedding-001\",\n",
        "      \"content\": {\n",
        "      \"parts\":[{\n",
        "        \"text\": \"How does the brain work?\"}]}, }, ]}' 2> /dev/null | grep -C 5 values"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "nPBk2k4xuql8"
      },
      "source": [
        "## Set the output dimensionality\n",
        "If you're using `gemini-embedding-001`, you can set the `output_dimensionality` parameter to create smaller embeddings.\n",
        "\n",
        "* `output_dimensionality` truncates the embedding (e.g., `[1, 3, 5]` becomes `[1,3]` when `output_dimensionality=2`).\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 22,
      "metadata": {
        "id": "ny3bOQK1ut2_"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "  \"embedding\": {\n",
            "    \"values\": [\n",
            "      -0.02342152,\n",
            "      0.01676572,\n",
            "      0.009261323,\n",
            "      -0.06383,\n",
            "      -0.0026262768,\n",
            "      0.0010187156,\n",
            "      -0.01125684,\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "\n",
        "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GEMINI_API_KEY\" \\\n",
        "-H 'Content-Type: application/json' \\\n",
        "-d '{\"model\": \"models/gemini-embedding-001\",\n",
        "    \"output_dimensionality\":256,\n",
        "    \"content\": {\n",
        "    \"parts\":[{\n",
        "      \"text\": \"Hello world\"}]}, }' 2> /dev/null | head"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ObAdUvlk9x05"
      },
      "source": [
        "## Use `task_type` to provide a hint to the model how you'll use the embeddings\n",
        "\n",
        "Let's look at all the parameters the embed_content method takes. There are four:\n",
        "\n",
        "* `model`: Required. Must be `models/gemini-embedding-001` or `models/text-embeddings-004`.\n",
        "* `content`: Required. The content that you would like to embed.\n",
        "* `task_type`: Optional. The task type for which the embeddings will be used. See below for possible values.\n",
        "\n",
        "`task_type` is an optional parameter that provides a hint to the API about how you intend to use the embeddings in your application.\n",
        "\n",
        "The following task_type parameters are accepted:\n",
        "\n",
        "* `RETRIEVAL_QUERY` : The given text is a query in a search/retrieval setting.\n",
        "* `RETRIEVAL_DOCUMENT`: The given text is a document from the corpus being searched.\n",
        "* `SEMANTIC_SIMILARITY`: The given text will be used for Semantic Textual Similarity (STS).\n",
        "* `CLASSIFICATION`: The given text will be classified.\n",
        "* `CLUSTERING`: The embeddings will be used for clustering.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 23,
      "metadata": {
        "id": "NwzsJmRrAo-t"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "  \"embedding\": {\n",
            "    \"values\": [\n",
            "      -0.026189324,\n",
            "      0.003135996,\n",
            "      0.01789595,\n",
            "      -0.08768083,\n",
            "      -0.0034239523,\n",
            "      0.018811652,\n",
            "      -0.0107915355,\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "\n",
        "curl \"https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GEMINI_API_KEY\" \\\n",
        "-H 'Content-Type: application/json' \\\n",
        "-d '{\"model\": \"models/gemini-embedding-001\",\n",
        "    \"content\": {\n",
        "    \"parts\":[{\n",
        "      \"text\": \"Hello world\"}]},\n",
        "    \"task_type\": \"RETRIEVAL_DOCUMENT\" \n",
        "    }' 2> /dev/null | head"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "jXkRYBhbB_b2"
      },
      "source": [
        "## Learning more\n",
        "\n",
        "* Learn more about `gemini-embedding-001` [here](https://ai.google.dev/gemini-api/docs/embeddings).\n",
        "*   Explore more examples in the [cookbook](https://github.com/google-gemini/cookbook).\n"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "name": "Embeddings_REST.ipynb",
      "toc_visible": true
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}
